
#********************************************************************************
# IBM Spectrum Protect Plus vSnap disk performance test tool
#
# name:    README.txt
# version: 1.4c
#
# Notice: This program is provided as a tool intended for use by IBM Internal,
#         IBM Business Partners, and IBM Customers. This program is provided as is,
#         without support, and without warranty of any kind expressed or implied.
#
# (C) Copyright International Business Machines Corp. 2013, 2021
#********************************************************************************

OVERVIEW
  The vnsapperf.pl tool is useful for evaluating the performance of storage used
  by vSnap prior to going in to production.  The tool builds around the ldeedee
  tool which is able to generate pseudo-random data that is useful for more
  accurate performance measurements when vSnap is using compression and deduplication.

  As a pre-requisite, the vSnap software must be installed and a vSnap pool must be
  created and mounted.  For more information on creating a vSnap pool, consult the
  IBM Spectrum Protect Plus blueprint which are available at 
  http://ibm.biz/IBMSpectrumProtectPlusBlueprints

  There are currently two workloads implemented, seqwrite and seqread, which are
  intended to simulate the large seq write and read workload driven by backup and
  restore.  In addition, a third cleanup worklod can be used to cleanup the data created
  by the tool.  See below for more details on cleanup.

INSTRUCTIONS
  Common use cases for the tool are best conveyed with a series of examples.
  View the tools on line help with:

  perl vsnapperf.pl -help

  1) Perform a sequential write of a 10GiB file using a single thread.

  perl vsnapperf.pl seqwrite -fileSize 10g

  2) Sequential write of two 10GiB files using two threads.  The -overwrite option is required
     to overwrite the file left behind fromthe previous test.  Do not take a snapshot of the volume
     after the write completes.

  perl vsnapperf.pl seqwrite -fileSize 10g -numVol 2 -snapshot no -overwrite=yes

  3) Perform five iterations of five threads writing 10GiB files.  Take a snapshot of all five volumes
     at the end of each iteration.
 
  perl vsnapperf.pl seqwrite -fileSize 10g -numVol 5 -iterations 5 -snapshot yes -overwrite=yes

  4) Perform two iterations of five thread reads of the 10 GiB files left from the previous test #3.

  perl vsnapperf.pl seqread -fileSize 10g -numVol 5 -iterations 2

  5) Resume another five iterations five thread 10GiB writes picking up where test #3 left off.

  perl vsnapperf.pl seqwrite -fileSize 10g -numVol 5 -iterations 10 -skipNum 5 -snapshot yes -overwrite=yes

  6) Cleanup the volumes left behind from previous tests.

  perl vsnapperf.pl cleanup -numVol 5

CLEANUP
  The tool will automatically cleanup the files and volumes the are created in cases where a single iteration 
  is run.  In cases where more than one iteration is performed, cleanup is not performed to facilitate
  restore testing.  The default cleanup behavior can be modified by specifying the -cleanup=yes|no option.
  Also, clean can be perform later by running vsnapperf.pl with the cleanup action.

EXAMPLE
  The following example was taken from the SPP blueprint Physical Supermicro reference.

  # perl vsnapperf.pl seqwrite -fileSize 5g -numVol 10 -random medium -snapshot no 
    -overwrite yes -iterations 3 -cleanup yes

===================================================================
: IBM Spectrum Protect Plus vSnap storage performance test  (Program version 1.4c)
:
: Running with action seqwrite
:
: Number of iterations: 3
: Skipping iterations:  0
: Number of volumes:    10
:
: Block size:   128k
: File size:    5g
: Syncwrite:    disabled
: Snapshots:    no
: Cleanup:      yes
: Random:       /dev/randmed
: Volumes:      /vsnap/vpool1/SPPvSnapPerf1 /vsnap/vpool1/SPPvSnapPerf2 /vsnap/vpool1/SPPvSnapPerf3 /vsnap/vpool1/SPPvSnapPerf4 /vsnap/vpool1/SPPvSnapPerf5 /vsnap/vpool1/SPPvSnapPerf6 /vsnap/vpool1/SPPvSnapPerf7 /vsnap/vpool1/SPPvSnapPerf8 /vsnap/vpool1/SPPvSnapPerf9 /vsnap/vpool1/SPPvSnapPerf10
:
===================================================================
: Beginning I/O test.
: Run 1. Output: vsnapperf1.txt Status: COMPLETE   Seconds: 123.58  Total GiB: 50.0  MiB/sec: 414.30  IOPS: 3314.39
: Run 2. Output: vsnapperf2.txt Status: COMPLETE   Seconds: 116.95  Total GiB: 50.0  MiB/sec: 437.79  IOPS: 3502.29
: Run 3. Output: vsnapperf3.txt Status: COMPLETE   Seconds: 155.60  Total GiB: 50.0  MiB/sec: 329.05  IOPS: 2632.37
: All iterations complete!
:
: Total processed    (GiB):     150.0
: Minimum throughput (MiB/sec): 329.05
: Maximum throughput (MiB/sec): 437.79
: Average throughput (MiB/sec): 393.71
:
: Cleaning up volumes.  Please be patient, this can take a while ...
: Cleaning volume vpool1/SPPvSnapPerf1
: Cleaning volume vpool1/SPPvSnapPerf2
: Cleaning volume vpool1/SPPvSnapPerf3
: Cleaning volume vpool1/SPPvSnapPerf4
: Cleaning volume vpool1/SPPvSnapPerf5
: Cleaning volume vpool1/SPPvSnapPerf6
: Cleaning volume vpool1/SPPvSnapPerf7
: Cleaning volume vpool1/SPPvSnapPerf8
: Cleaning volume vpool1/SPPvSnapPerf9
: Cleaning volume vpool1/SPPvSnapPerf10
===================================================================


CHANGE HISTORY
  v1.2   Introduced cleanup functionality.
  v1.4   Introduced improved pseudo-random data generation targetting closer to 2 to 1 compression 
         with randmed.
  v1.4b  Bugfix for excessive dedup savings resulting from the improved pseudo-random data generation
         and improved logging.
  v1.4c  Change default -bSize blocksize parameter from 256K to 128K
